home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / BARNET / FREENET / GAMMANS / SOCKFS-0.ZIP / !Readme next >
Text File  |  1997-09-07  |  7KB  |  143 lines
  1. SocketFS Readme
  2. ===============
  3.  
  4.  
  5. This is the 'Readme' for the first ALPHA release of socketfs, a socket
  6. filing system for RISC-OS.
  7. As it is the first ALPHA release, socketFS undoubtely has many bugs,
  8. please feel free to e-mail with details of any (or all) bugs you find,
  9. although I would ask you to first check see if the Bugs is alreadly
  10. known by checking the distrubutions BUGS and FAQ files.
  11. I would also ask you to e-mail me any and let me know if you find it
  12. useful.
  13.  
  14. What does it do then?
  15. ---------------------
  16. Quite simply socketfs allows you to open a BSD socket as if it were a
  17. file. SocketFS allows multiple type of addressing to be using and you
  18. can easily add you own function to map filenames to sockets, although at
  19. this stage new functions have to be assembled in, the underlying
  20. mechanism is extensiable and if enough interest is shown, a
  21. SWI SocketFS_RegisterAddressType or simliar could be implemented.
  22. SocketFS uses the specialfield to decide which mapping to use, currently
  23. the only mapping supported is 'IPv4'. This is probaly a bad name for it
  24. as the mapping is really based on gethostbyname(). This is also the
  25. default specialfield. Using any other special field will result in a
  26. file not found or similiar.
  27.  
  28. Currently any socket which you can open with a Internet module (eg. Acorn
  29. Internet or FreeNet) can be opened with socketfs.
  30.  
  31. How do I use it?
  32. ----------------
  33. Like any other streaming filesystem. Open a file and write to it, the
  34. only clever bit you need to know about is the filename.
  35. Lets examine a possible  filename field by field. The general format is
  36.  
  37.    socketFS#map::proto.$.remote_host\rport.local_host\lport
  38.  
  39.   map         - Defaults to 'IPv4', and can be either 'IPv4' or 's2fd'.
  40.                 T
  41.  
  42.   proto       - Generally this will be tcp, although you might be able to
  43.                 get some use out of udp. There are others but these are
  44.                 the only ones the Internet modules support (AFAIK anyway)
  45.                 ergo the only ones I support. Be aware if you try udp or
  46.                 other protocol sockets are created as SOCK_STREAM, which
  47.                 might cause you problems.
  48.                 The 's2fd' mapping currently ignores thsi field, although may
  49.                 use it for flags in a later module version.
  50.  
  51.   remote_host - This is the machine you want to connect to. Specify the
  52.                 host name the same way as you would for any usual
  53.                 internet program but replace the '.'s with '/' in the
  54.                 reverse manner to risc-os usually does for UNIX
  55.                 filenames. The means www.demon.co.uk becomes
  56.                 www/demon/co/uk . Note that '/' aren't required if the
  57.                 hostname has no dots so just 'localhost will work.
  58.                 In 's2fd' this is a socket handle and a new filehandle
  59.                 is then return bound to this socket.
  60.  
  61.   rport       - This is the port on the remote machine you want to
  62.                 connect to. You can specify it by service name or
  63.                 number. In the example above you would specify '80' or
  64.                 'www'. (Assuming you where try to download web pages
  65.                 anyway.)
  66.  
  67.   local_host  - This is the first optional part, and specifies which
  68.                 interface on your local machine you wish to initiate the
  69.                 connection from. It uses the same format to remote_host.
  70.  
  71.   lport       - The is another optional part, an specifies which port
  72.                 the socket uses on your local machine. It uses the same
  73.                 format as rport. This and the previous part are passed
  74.                 to the internet module using bind.
  75.  
  76.  
  77.  This means if you want to save a web page off, something like this
  78. could do the trick. (IN Basic!)
  79.  
  80.     File%=OPENOUT("ADFS::4.$.webpage")
  81.     Web%=OPENUP("socketfs::tcp.$.www/demon/co/uk\www")
  82.     A$ = "GET /index.html"
  83.     BPUT#Web%,A$
  84.     BPUT#Web%,10 : REM Write end of line...
  85.     WHILE NOT EOF#Web%
  86.       BPUT#File%,BGET#Web%
  87.      ENDWHILE
  88.     CLOSE#Web% :REM Release this at end of tcp stream...
  89.     CLOSE#File%
  90.     OSCLI("settype adfs::4.$.webpage faf"):REM faf=html
  91.  
  92.  
  93. Ok, So what use is it
  94. ---------------------
  95. Well it makes internet sockets slightly easier to use, and allow you
  96. to treat them like files. Specifically the UnixLib people might find it
  97. useful to allow file operations on sockets as you can in Unix. Although
  98. at the moment listen(), accept() are slightly difficult. 
  99.  
  100.  
  101. Is there anything it can't do that I should now about
  102. -----------------------------------------------------
  103. I haven't spend anytime working on the implentation of whole file
  104. operations, so *save may or may not work. NO Guarantees.
  105. Also socketfs: does not support renaming as IP essentialy doesn't
  106. allow streams to move between sockets (or interfaces). I might use this
  107. file system semantics for accept() later though.
  108. Finally it has one other feature, the current version of the module uses
  109. blocking sockets, although this means it will wait for data on a socket
  110. withouy returning a error if there is none waiting. One of two things
  111. will then happen, first it will hang the whole machine, or if you're running
  112. freenet or Acorn Internet 5.00 or higher just that taskwindow. 
  113. Freenet still has the disadvantage that fileswitch/taskwindow seem to 
  114. block other FS calls to thesame handle while the first is waiting. This 
  115. is fine for simplex and  half-duplex protocols but if you need full-duplex
  116. across Taskwindows, your could recompile the module with -DFIOMODE=FIONBIO
  117. which will force the module to use non-blocking sockets as default.
  118.  
  119. Final Comments
  120. --------------
  121. It would be nice to add ioctl, and socket_select fuctionality to the
  122. filing system, but I haven't come up with a nice way of doing those
  123. yet. While my own SWI interace would work - bear in mind that socketfs uses
  124. fileswitch to do the SocketHandle<-->FileHandle mapping, so socketfs can't
  125. do this itself as it knows nothing about fileswitch's handles. 
  126. I suppose it would be possible to attribute and filetype, assigning different
  127. meanings to these than is usual, but it's not a nice solution.
  128.  
  129. I'll take a moment here to remind you that socketFS is
  130. distrubuted under the conditions outlined in the accompanying file called
  131. 'COPYING', currently this is version 2 of the GPL, however I find GPLs virus
  132. like ablities a little harsh for my tastes, so you'll find me relatively open
  133. on allowing limited distributions under other licenses. 
  134. I would also ask you to let me know your experiences, with the software 
  135. by e-mail if possible.
  136. I will also welcome bug reports and patches (context diffs please), and 
  137. feature requests. I can be reached at <rgammans@compsurg.demon.co.uk>,  
  138. and could I please ask if you do e-mail me, can you mention socketfs in
  139. the subject line.
  140.  
  141. Roger Gammans
  142. 18 Aug 1997
  143.